home *** CD-ROM | disk | FTP | other *** search
/ Visual Cafe 3 / Visual Cafe 3.ISO / Vcafe / JFC.bin / View.java < prev    next >
Text File  |  1998-06-30  |  17KB  |  492 lines
  1. /*
  2.  * @(#)View.java    1.21 98/04/09
  3.  * 
  4.  * Copyright (c) 1997 Sun Microsystems, Inc. All Rights Reserved.
  5.  * 
  6.  * This software is the confidential and proprietary information of Sun
  7.  * Microsystems, Inc. ("Confidential Information").  You shall not
  8.  * disclose such Confidential Information and shall use it only in
  9.  * accordance with the terms of the license agreement you entered into
  10.  * with Sun.
  11.  * 
  12.  * SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF THE
  13.  * SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
  14.  * IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
  15.  * PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR ANY DAMAGES
  16.  * SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING
  17.  * THIS SOFTWARE OR ITS DERIVATIVES.
  18.  * 
  19.  */
  20. package com.sun.java.swing.text;
  21.  
  22. import java.awt.Container;
  23. import java.awt.Graphics;
  24. import java.awt.Shape;
  25. import java.awt.Rectangle;
  26. import java.awt.Point;
  27. import com.sun.java.swing.event.*;
  28.  
  29. /**
  30.  * A view of some portion of document model.  Provides
  31.  * a mapping to model coordinates from view coordinates
  32.  * and a mapping to view coordinates from model coordinates.
  33.  * A view also provides rendering and layout services.
  34.  *
  35.  * @author  Timothy Prinzing
  36.  * @version 1.21 04/09/98
  37.  */
  38. public abstract class View {
  39.  
  40.     /**
  41.      * Creates a new View object.
  42.      *
  43.      * @param elem the element to represent
  44.      */
  45.     public View(Element elem) {
  46.     this.elem = elem;
  47.     }
  48.  
  49.     /**
  50.      * Returns the parent of the view.
  51.      *
  52.      * @return the parent, null if none
  53.      */
  54.     protected final View getParent() {
  55.     return parent;
  56.     }
  57.  
  58.     /**
  59.      * Determines the preferred span for this view along an
  60.      * axis.
  61.      *
  62.      * @param axis may be either View.X_AXIS or View.Y_AXIS
  63.      * @returns  the span the view would like to be rendered into.
  64.      *           Typically the view is told to render into the span
  65.      *           that is returned, although there is no guarantee.  
  66.      *           The parent may choose to resize or break the view.
  67.      * @see View#getPreferredSpan
  68.      */
  69.     public abstract float getPreferredSpan(int axis);
  70.  
  71.     /**
  72.      * Child views can call this on the parent to indicate that
  73.      * the preference has changed and should be reconsidered
  74.      * for layout.  By default this just propagates upward to 
  75.      * the next parent.  The root view will call 
  76.      * <code>revalidate</code> on the associated text component.
  77.      *
  78.      * @param child the child view
  79.      * @param width true if the width preference has changed
  80.      * @param height true if the height preference has changed
  81.      * @see com.sun.java.swing.JComponent#revalidate
  82.      */
  83.     public void preferenceChanged(View child, boolean width, boolean height) {
  84.     getParent().preferenceChanged(child, width, height);
  85.     }
  86.  
  87.     /**
  88.      * Determines the desired alignment for this view along an
  89.      * axis.  By default this is simply centered.
  90.      *
  91.      * @param axis may be either View.X_AXIS or View.Y_AXIS
  92.      * @returns The desired alignment.  This should be a value
  93.      *   >= 0.0 and <= 1.0 where 0 indicates alignment at the
  94.      *   origin and 1.0 indicates alignment to the full span
  95.      *   away from the origin.  An alignment of 0.5 would be the
  96.      *   center of the view.
  97.      */
  98.     public float getAlignment(int axis) {
  99.     return 0.5f;
  100.     }
  101.  
  102.     /**
  103.      * Renders using the given rendering surface and area on that
  104.      * surface.  The view may need to do layout and create child
  105.      * views to enable itself to render into the given allocation.
  106.      *
  107.      * @param g the rendering surface to use
  108.      * @param allocation the allocated region to render into
  109.      * @see View#paint
  110.      */
  111.     public abstract void paint(Graphics g, Shape allocation);
  112.  
  113.     /**
  114.      * Establishes the parent view for this view.  This is
  115.      * guaranteed to be called before any other methods if the
  116.      * parent view is functioning properly.  This is also
  117.      * the last method called, since it is called to indicate
  118.      * the view has been removed from the hierarchy as 
  119.      * well.  If this is reimplemented, 
  120.      * <code>super.setParent()</code> should be called.
  121.      *
  122.      * @param parent the new parent, or null if the view is
  123.      *  being removed from a parent it was previously added
  124.      *  to
  125.      */
  126.     public void setParent(View parent) {
  127.     this.parent = parent;
  128.     }
  129.  
  130.     /** 
  131.      * Returns the number of views in this view.  Since
  132.      * the default is to not be a composite view this
  133.      * returns 0.
  134.      *
  135.      * @return the number of views >= 0
  136.      * @see View#getViewCount
  137.      */
  138.     public int getViewCount() {
  139.     return 0;
  140.     }
  141.  
  142.     /** 
  143.      * Gets the nth child view.  Since there are no
  144.      * children by default, this returns null.
  145.      *
  146.      * @param n the number of the view to get, >= 0 && < getViewCount()
  147.      * @return the view
  148.      */
  149.     public View getView(int n) {
  150.     return null;
  151.     }
  152.  
  153.     /**
  154.      * Fetches the allocation for the given child view. 
  155.      * This enables finding out where various views
  156.      * are located, without assuming the views store
  157.      * their location.  This returns null since the
  158.      * default is to not have any child views.
  159.      *
  160.      * @param index the index of the child, >= 0 && < getViewCount()
  161.      * @param a  the allocation to this view.
  162.      * @return the allocation to the child
  163.      */
  164.     public Shape getChildAllocation(int index, Shape a) {
  165.     return null;
  166.     }
  167.  
  168.     /**
  169.      * Provides a mapping from the document model coordinate space
  170.      * to the coordinate space of the view mapped to it.
  171.      *
  172.      * @param pos the position to convert >= 0
  173.      * @param a the allocated region to render into
  174.      * @return the bounding box of the given position is returned
  175.      * @exception BadLocationException  if the given position does
  176.      *   not represent a valid location in the associated document
  177.      * @see View#modelToView
  178.      */
  179.     public abstract Shape modelToView(int pos, Shape a) throws BadLocationException;
  180.  
  181.     /**
  182.      * Provides a mapping from the view coordinate space to the logical
  183.      * coordinate space of the model.
  184.      *
  185.      * @param x the X coordinate >= 0
  186.      * @param y the Y coordinate >= 0
  187.      * @param a the allocated region to render into
  188.      * @return the location within the model that best represents the
  189.      *  given point in the view >= 0
  190.      * @see View#viewToModel
  191.      */
  192.     public abstract int viewToModel(float x, float y, Shape a);
  193.  
  194.     /**
  195.      * Gives notification that something was inserted into the document 
  196.      * in a location that this view is responsible for.
  197.      *
  198.      * @param e the change information from the associated document
  199.      * @param a the current allocation of the view
  200.      * @param f the factory to use to rebuild if the view has children
  201.      * @see View#insertUpdate
  202.      */
  203.     public void insertUpdate(DocumentEvent e, Shape a, ViewFactory f) {
  204.     }
  205.  
  206.     /**
  207.      * Gives notification from the document that attributes were removed 
  208.      * in a location that this view is responsible for.
  209.      *
  210.      * @param e the change information from the associated document
  211.      * @param a the current allocation of the view
  212.      * @param f the factory to use to rebuild if the view has children
  213.      * @see View#removeUpdate
  214.      */
  215.     public void removeUpdate(DocumentEvent e, Shape a, ViewFactory f) {
  216.     }
  217.  
  218.     /**
  219.      * Gives notification from the document that attributes were changed
  220.      * in a location that this view is responsible for.
  221.      *
  222.      * @param e the change information from the associated document
  223.      * @param a the current allocation of the view
  224.      * @param f the factory to use to rebuild if the view has children
  225.      * @see View#changedUpdate
  226.      */
  227.     public void changedUpdate(DocumentEvent e, Shape a, ViewFactory f) {
  228.     }
  229.  
  230.     /**
  231.      * Fetches the model associated with the view.
  232.      *
  233.      * @return the view model, null if none
  234.      * @see View#getDocument
  235.      */
  236.     public Document getDocument() {
  237.     return elem.getDocument();
  238.     }
  239.  
  240.     /**
  241.      * Fetches the portion of the model that this view is
  242.      * responsible for.
  243.      *
  244.      * @return the starting offset into the model >= 0
  245.      * @see View#getStartOffset
  246.      */
  247.     public int getStartOffset() {
  248.     return elem.getStartOffset();
  249.     }
  250.  
  251.     /**
  252.      * Fetches the portion of the model that this view is
  253.      * responsible for.
  254.      *
  255.      * @return the ending offset into the model >= 0
  256.      * @see View#getEndOffset
  257.      */
  258.     public int getEndOffset() {
  259.     return elem.getEndOffset();
  260.     }
  261.  
  262.     /**
  263.      * Fetches the structural portion of the subject that this
  264.      * view is mapped to.  The view may not be responsible for the
  265.      * entire portion of the element.
  266.      *
  267.      * @return the subject
  268.      * @see View#getElement
  269.      */
  270.     public Element getElement() {
  271.     return elem;
  272.     }
  273.  
  274.     /**
  275.      * Tries to break this view on the given axis.  This is
  276.      * called by views that try to do formatting of their
  277.      * children.  For example, a view of a paragraph will
  278.      * typically try to place its children into row and 
  279.      * views representing chunks of text can sometimes be 
  280.      * broken down into smaller pieces.
  281.      * <p>
  282.      * This is implemented to return the view itself, which
  283.      * represents the default behavior on not being
  284.      * breakable.  If the view does support breaking, the
  285.      * starting offset of the view returned should be the
  286.      * given offset, and the end offset should be less than
  287.      * or equal to the end offset of the view being broken.
  288.      *
  289.      * @param axis may be either View.X_AXIS or View.Y_AXIS
  290.      * @param offset the location in the document model
  291.      *   that a broken fragment would occupy >= 0.  This
  292.      *   would be the starting offset of the fragment
  293.      *   returned.
  294.      * @param pos the position along the axis that the
  295.      *  broken view would occupy >= 0.  This may be useful for
  296.      *  things like tab calculations.
  297.      * @param len specifies the distance along the axis
  298.      *  where a potential break is desired >= 0.  
  299.      * @return the fragment of the view that represents the
  300.      *  given span, if the view can be broken.  If the view
  301.      *  doesn't support breaking behavior, the view itself is
  302.      *  returned.
  303.      * @see ParagraphView
  304.      */
  305.     public View breakView(int axis, int offset, float pos, float len) {
  306.     return this;
  307.     }
  308.  
  309.     /**
  310.      * Create a view that represents a portion of the element.
  311.      * This is potentially useful during formatting operations
  312.      * for taking measurements of fragments of the view.  If 
  313.      * the view doesn't support fragmenting (the default), it 
  314.      * should return itself.  
  315.      *
  316.      * @param p0 the starting offset >= 0.  This should be a value
  317.      *   greater or equal to the element starting offset and
  318.      *   less than the element ending offset.
  319.      * @param p1 the ending offset > p0.  This should be a value
  320.      *   less than or equal to the elements end offset and
  321.      *   greater than the elements starting offset.
  322.      * @returns the view fragment, or itself if the view doesn't
  323.      *   support breaking into fragments.
  324.      * @see LabelView
  325.      */
  326.     public View createFragment(int p0, int p1) {
  327.     return this;
  328.     }
  329.  
  330.     /**
  331.      * Determines how attractive a break opportunity in 
  332.      * this view is.  This can be used for determining which
  333.      * view is the most attractive to call <code>breakView</code>
  334.      * on in the process of formatting.  A view that represents
  335.      * text that has whitespace in it might be more attractive
  336.      * than a view that has no whitespace, for example.  The
  337.      * higher the weight, the more attractive the break.  A
  338.      * value equal to or lower than <code>BadBreakWeight</code>
  339.      * should not be considered for a break.  A value greater
  340.      * than or equal to <code>ForcedBreakWeight</code> should
  341.      * be broken.
  342.      * <p>
  343.      * This is implemented to provide the default behavior
  344.      * of returning <code>BadBreakWeight</code> unless the length
  345.      * is greater than the length of the view in which case the 
  346.      * entire view represents the fragment.  Unless a view has
  347.      * been written to support breaking behavior, it is not
  348.      * attractive to try and break the view.  An example of
  349.      * a view that does support breaking is <code>LabelView</code>.
  350.      * An example of a view that uses break weight is 
  351.      * <code>ParagraphView</code>.
  352.      *
  353.      * @param axis may be either View.X_AXIS or View.Y_AXIS
  354.      * @param pos the potential location of the start of the 
  355.      *   broken view >= 0.  This may be useful for calculating tab
  356.      *   positions.
  357.      * @param len specifies the relative length from <em>pos</em>
  358.      *   where a potential break is desired >= 0.
  359.      * @return the weight, which should be a value between
  360.      *   ForcedBreakWeight and BadBreakWeight.
  361.      * @see LabelView
  362.      * @see ParagraphView
  363.      * @see BadBreakWeight
  364.      * @see GoodBreakWeight
  365.      * @see ExcellentBreakWeight
  366.      * @see ForcedBreakWeight
  367.      */
  368.     public int getBreakWeight(int axis, float pos, float len) {
  369.     if (len > getPreferredSpan(axis)) {
  370.         return GoodBreakWeight;
  371.     }
  372.     return BadBreakWeight;
  373.     }
  374.  
  375.     /**
  376.      * Determines the resizability of the view along the
  377.      * given axis.  A value of 0 or less is not resizable.
  378.      *
  379.      * @param axis View.X_AXIS or View.Y_AXIS
  380.      * @return the weight
  381.      */
  382.     public int getResizeWeight(int axis) {
  383.     return 0;
  384.     }
  385.  
  386.     /**
  387.      * Sets the size of the view.  This should cause 
  388.      * layout of the view, if it has any layout duties.
  389.      * The default is to do nothing.
  390.      *
  391.      * @param width the width >= 0
  392.      * @param height the height >= 0
  393.      */
  394.     public void setSize(float width, float height) {
  395.     }
  396.  
  397.     /**
  398.      * Fetches the container hosting the view.  This is useful for
  399.      * things like scheduling a repaint, finding out the host 
  400.      * components font, etc.  The default implementation
  401.      * of this is to forward the query to the parent view.
  402.      *
  403.      * @return the container, null if none
  404.      */
  405.     public Container getContainer() {
  406.     View v = getParent();
  407.     return (v != null) ? v.getContainer() : null;
  408.     }
  409.  
  410.     /**
  411.      * Fetches the ViewFactory implementation that is feeding
  412.      * the view hierarchy.  Normally the views are given this
  413.      * as an argument to updates from the model when they
  414.      * are most likely to need the factory, but this
  415.      * method serves to provide it at other times.
  416.      *
  417.      * @return the factory, null if none
  418.      */
  419.     public ViewFactory getViewFactory() {
  420.     View v = getParent();
  421.     return (v != null) ? v.getViewFactory() : null;
  422.     }
  423.  
  424.     /**
  425.      * The weight to indicate a view is a bad break
  426.      * opportunity for the purpose of formatting.  This
  427.      * value indicates that no attempt should be made to
  428.      * break the view into fragments as the view has 
  429.      * not been written to support fragmenting.
  430.      * @see #getBreakWeight
  431.      * @see GoodBreakWeight
  432.      * @see ExcellentBreakWeight
  433.      * @see ForcedBreakWeight
  434.      */
  435.     public static final int BadBreakWeight = 0;
  436.  
  437.     /**
  438.      * The weight to indicate a view supports breaking,
  439.      * but better opportunities probably exist.
  440.      * 
  441.      * @see #getBreakWeight
  442.      * @see BadBreakWeight
  443.      * @see GoodBreakWeight
  444.      * @see ExcellentBreakWeight
  445.      * @see ForcedBreakWeight
  446.      */
  447.     public static final int GoodBreakWeight = 1000;
  448.  
  449.     /**
  450.      * The weight to indicate a view supports breaking,
  451.      * and this represents a very attractive place to
  452.      * break.
  453.      *
  454.      * @see #getBreakWeight
  455.      * @see BadBreakWeight
  456.      * @see GoodBreakWeight
  457.      * @see ExcellentBreakWeight
  458.      * @see ForcedBreakWeight
  459.      */
  460.     public static final int ExcellentBreakWeight = 2000;
  461.  
  462.     /**
  463.      * The weight to indicate a view supports breaking,
  464.      * and must be broken to be represented properly 
  465.      * when placed in a view that formats it's children
  466.      * by breaking them.
  467.      *
  468.      * @see #getBreakWeight
  469.      * @see BadBreakWeight
  470.      * @see GoodBreakWeight
  471.      * @see ExcellentBreakWeight
  472.      * @see ForcedBreakWeight
  473.      */
  474.     public static final int ForcedBreakWeight = 3000;
  475.  
  476.     /**
  477.      * Axis for format/break operations.
  478.      */
  479.     public static final int X_AXIS = 0;
  480.  
  481.     /**
  482.      * Axis for format/break operations.
  483.      */
  484.     public static final int Y_AXIS = 1;
  485.  
  486.  
  487.     private View parent;
  488.     private Element elem;
  489.  
  490. };
  491.  
  492.